************************************ * CANIMATE.VBX - Release 1.00 * * (c) Componere Software * * - All Rights Reserved - * ************************************ On downloading this VBX, you should have received: CANIMATE.VBX <- A BETA level release of the animation control library GAME.EXE <- VBRUN200.DLL required to run GAME.MAK GAME.FRM BIRD.BMP <- A 3x2 matrix for cell animation README.TXT The "game" is a demo of a hero-type player walking back and forth across the stage. A fire is burning in the middle of the stage and every time he walks through it, he hops around a bit. A bird flits about overhead, flying in random patterns to demonstrate varying slopes of travel. The clouds moving overhead are in a control array, update at lesser intervals and move less on each update. The two trees at the bottom demonstrate Zposition; one is in the foreground, one in the background. Overview -------- CANIMATE will allow animation controls to be created and manipulated in Visual Basic. In the current release, only 2D animation is supported. There are two types of animation supported: sprite and cell animation. They may be used concurrently or separately. Sprite animation is moving an image about on the screen. Cell animation uses frames, or pictures of the same thing in various states of motion, much like a motion picture. Combining the two techniques results in a much more realistic mode of animation than either technique alone. A bird can beat its wings as it flies about the screen, for example. Sometimes only one is needed; a fire stays in one spot and flickers, while an arrow flies without ever changing its shape. CANIMATE accomplishes this through the use of two controls: Stage and Player. Stage is the background, a container in which Players are created. Players are animated (or not; they can be simply still pictures) objects to be displayed on the background. The Stage supplies keyboard and mouse input. It is a control which accepts focus. The Player is a potentially complex object. In the original design, there were to be several different types of animated objects. But as development proceeded, it became evident that all of them were really just the same object with some properties predefined, and rather than risk not allowing the combination that might be most desirable for a particular situation, a single object was created with all the properties available. Don't be frightened by its complexity; if one is created and a picture assigned, then it will show the picture and not do anything else. If sprite animation is required, the target coordinates are set and moving is enabled. If cell animation is needed, it gets a bit more complicated as described below. A bitmap assigned to a Player is assumed to be a single picture by default. However, if cell animation is required, the fastest and most efficient way to "package" all the frames is to put them in a single bitmap that is larger than a single frame. The cells are organized in a grid, much like a spreadsheet (only no lines!). On a row, from left to right, are images which should be shown in a logical sequence. If there are multiple logical sequences, then the other sequences are on other rows. For instance, let's say you have a player that is 48 pels high and 24 pels wide. On the first row you might have him face to the right, one picture with his feet together, one with them spread apart. On the second row you might have him do the same, only facing left. To do this, you create a bitmap that is 96 pels wide and 48 pels wide and draw (or paste - I suggest that somewhere you keep the images unique, but it's up to you, of course) the first row in the upper half and the second row in the second half. Then when this bitmap is assigned to a Player control, set XFrames and YFrames each to 2. Set Cycle to True (I know, I am getting ahead) and he runs in place. But set a target location off to the right, and off he goes. Set the FrameRow to 1 and a target off to the left and he walks that way. The example will help to clear this up a bit. Events for mouse clicks are generated if Player objects are clicked on. There are additional events that can be generated when a Player object arrives at a target location, runs into another Player object or completes a cycle of cell animation (has shown all the frames on a row). These events must be solicited; by default they are not reported, so that Player objects like a flickering fire will have minimal impact on performance. An important concept to remember is that every object on the Stage is a Player, but that does not mean that you have to move them all with keystrokes. Not at all. Generally speaking, one Player will be your "hero" or "heroine" and the others will be props, hazards, bullets or bad guys. Another important thing to note: There is a lot that can be done with animation besides game programming, such as sprucing up a logo display in the about box or even simulating screens for training. Planned enhancements will allow 3D scenes to be created, easing the creation of games such as adventures or golf where the player (or ball) moves in a room or landscape. If sound is a common request, it may be implemented, though the multimedia controls should work with ANIMATE without any problem. Perhaps sound might be desirable using the old voice functions for lesser/older machines. Suggestions are welcome. Now for some "legalese": CANIMATE is a licensed product of Componere Software. The version included is an evaluation version and may be used to develop for any length of time you wish; however, you cannot ship it with a product, even if that that product is free. The evaluation version may be freely redistributed as long as all the files accompany it, and it is not distributed as part of another product. A note to BBS operators: A window will appear in the background indicating that this is an unregistered version. This is to be expected and it is an indication that it is in fact the evaluation version. There is tamper detection logic included which requires that the evaluation copyright window not be disabled. You may purchase a registered version from: Componere Software 1381 Kildaire Farm Rd #119 Cary, NC, 27511-5525 There are two prices for CANIMATE.VBX. If you want to redistribute applications which use the animation provided, it is $39 (US dollars only) for unlimited redistribution rights of the runtime version, plus a single use license for the development version. If you only want the development version for personal use, with no redistribution rights, you can order it for $19. The advantage of the development version over the provided demo version is that you will be notified of updates, given support and you will be able to sleep at night :) An order form is included in ORDER.TXT. Please use it to order. If you have any questions, contact: EMail: Componere@aol.com Trouble shooting is listed before the explanation of properties just to raise your level of awareness that the section exists. There are some concepts in this VBX which may not be immediately obvious, most notably having to set a property to get motion or cycling to begin, and receiving events for collisions, arrivals and cycles. ******************** * TROUBLE SHOOTING * ******************** Common Problems --------------- (stuff I even forget myself :) IF NOTHING MOVES OR CYCLES THROUGH FRAMES: Don't forget to set the Interval values for Stage and Player!!!! Don't forget to set the Interval values for Stage and Player!!!! If it is zeroed, I assume that you want to freeze frame; in fact, that is the best way to implement a pause in your game. IF A PLAYER DOESN'T MOVE OR STOPS MOVING: To get a player to move, set TargetX, TargetY and set Moving to True. When the player arrives at the target, it will stop and Moving will be set to False; you have to retarget and set Moving true again to get more movement. IF A PLAYER NEVER CYCLES THROUGH FRAMES: Cycling must be set to True to use cell animation. Cycling will remain True after a Cycle event (unlike Moving) unless you turn it off. IF YOU AREN'T GETTING ANY EVENTS FOR A PLAYER: You must set the flag for the events you want (CycleEvents, CollideEvents, TargetEvents) or you will not get any events. One of the ways the speed is maintained is by not calling the VB handler unless it is requested. Also, see the top tip again - Interval must be non zero!! IF YOU AREN'T GETTING COLLISION EVENTS FOR A PLAYER: The CollideEvent must be True and the CollideID of the Player objects which it runs into must not be zero. IF COLORS GET CONFUSED WHEN MULTIPLE BITMAPS ARE UP: All the bitmaps must share the same pallette. If you use the Windows Paintbrush program, they will all use the system pallette. IF MOVEMENT IS "ODD": Make sure that your values for the grid are right, and that the frames are evenly spread. Check the movement amounts and remember that they must be in twips. Make sure you don't do too much processing at cycle events. IF COLORS SEEM TO MIX WHILE MOVING: Some colors are composite colors; if you zoom in on them in paint, you will see alternating bits of different colors which appear as a single color when zoomed out. If you pick one of these as your TransparentColor, then these bits of color will allow the background to come through. You need to make sure that the color you pick to be transparent is not used at all in the foreground of the picture; not even "mixed" in another color. A tip - you can get some interesting effects by doing this on purpose, for ghosting or flames. EVENTS DON'T COME IN IF A MESSAGE BOX IS UP: That's the way VB works. Events are thrown away when a message box comes up until it goes away. You should set the Stage Interval to zero while it is up to freeze animation, unless missing events is unimportant. ANIMATION STOPS WHILE DEBUGGING: Only while in break mode. This is on purpose. You would find it impossible to debug if events continued to happen (they get ignored by VB) while in break. This also allows you to examine the "state of the world" during break at your own pace. Each time you Go, it runs full speed. ********************************* *Controls, properties and events* ********************************* Stage Standard Properties: BackColor BorderStyle Height Index Left Name Tag Top Visible Width Special Properties: Interval - This is the number of milliseconds to set timer events for animating objects. Also see interval for Player control. Interval for the Stage control determines the granularity at which Players can be animated. Picture - An optional bitmap. A stage may either use a bitmap or background color. Events: Sub Stage1_Click () Standard mouse click event Sub Stage1_KeyDown (WP As Integer) A key was pressed. A WM_KEYDOWN message was received. WP is the wParam or virtual key code. Sub Stage1_KeyUp (WP As Integer) A key was released. A WM_KEYUP message was received. WP is the wParam or virtual key code. Sub Stage1_KeyChar (WP As Integer) A keystroke was translated into a character. A WM_CHAR message was received. WP is the character as an int. Player Standard Properties: Height Index Left Name Tag Top Visible Width NOTE: Height and Width are a little different with a Player than with most other controls. Frames are not stretched to fill a larger rectangle; the extra space is ignored. If the space is too small, it will not clip the frame being displayed, nor shrink it. So the size of a Frame (or Picture if XFrames and YFrames are both 1 or less) really determines control size. IMPORTANT: All position and size properties are in twips. ScaleMode doesn't work since Players are inside of the Stage object, and there doesn't seem to be any clean workaround. Special Properties: CollideEvents - If set to True, events will be generated if the Player collides with another visible Player control which has a non zero CollideID. CollideID - This is used to identify the Player or type of Player in a collision. It does not have to be unique. For instance, you might set all hazards to 1 and walls to 2 in a game. Then if you get a collide event with a 1, you can "kill" your player, while simply stopping for a 2. CycleEvents - If set to True, events will be generated each time all the frames on a row have been shown. Cycling - If True, the Player will cycle through frames on a row. This enables cell animation. Frame - This is a number from 0 to XFrames-1 which indicates the frame currently being displayed. FrameRow - This is a number from 0 to YFrames-1 which indicates which row of frames are currently being displayed. Interval - This indicates how often the Player should be updated. Each time an update occurs, the Player will be moved if it is moving toward a target and/or have the next frame shown if cell animation is being used. This is a multiplier for the Stage's Interval. If the Interval of the Stage is set to 111 and the Interval of the Player is set to 3, it will be updated every 333 milliseconds (approx) or about 3 times a second, for example. Moving - If set to True, the Player will begin moving toward the target location if/when it is different than the current location. Picture - The bitmap. If XFrames and YFrames are 1 or 0, then it is simply a single picture. Otherwise, it is a collection of frames all of equal size arranged in a grid. TargetEvents - If set to True, events will be generated when the Player reaches a target location. TargetX - The target location X coordinate in twips. TargetY - The target location Y coordinate in twips. TransparentColor - The color in the bitmap which should not paint over objects or background beneath. Also, a collision does not occur if either of the overlapping areas is completely transparent. Text - A character string to write into the control. TextColor - The color to use for text XFrames - The number of frames on each row if > 1. XMoveAmount - The maximum number of twips to move on each update in the X direction when moving toward a target. The Player may move less in some cases as dictated by slope of the line of travel or proximity to the target location. YFrames - The number of rows of frames in the bitmap if > 1 YMoveAmount - The maximum number of twips to move on each update in the Y direction when moving toward a target. The Player may move less in some cases as dictated by slope of the line of travel or proximity to the target location. ZPosition - Determines paint order; the lower the number the later it is painted (0 = topmost). If this is not set, the order will be the order in which the controls are created. Collisions may still be reported even if ZOrders are not equal. You might choose to set the ZOrder of some Player control, like a bush, lower than a Player that is your "hero" so that the hero can hide behind the bush (some hero :) Events: Sub Player1_AtTarget () The player was in motion and has arrived at the target location. TargetEvents must be True for this event to be generated. Sub Player1_Click () The standard mouse click event. Sub Player1_Collide (ID As Integer) The Player is in motion and has collided with another Player control which has a non zero CollideID. The ID is the CollideID of the other Player control. CollideEvents must be True for this event to be generated. Sub Player1_Cycle () The Player is cycling through frame animation and has completed a cycle (shown all the images on a frame row). If nothing is done to change the state, the Player will continue cycling, starting at Frame 0 on the current FrameRow. CycleEvents must be True for this event to be generated.